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FOREWORD 


This  report  is  one  in  a series  of  guidebooks  intended  to  assist 
System  Program  Office  personnel  in  software  acquisition  management. 

The  contents  of  the  guidebooks  will  be  revised  periodically  to  reflect 
changes  in  software  acquisition  policies  and  practices  and  as  the 
result  of  feedback  from  users. 

This  series  of  guidebooks  is  being  prepared  under  the  direction 
of  Electronic  Systems  Division  (AFSC) , Information  Systems  Technology 
Applications  Office  (MCI).  Contributions  were  made  by  the  following 
ESD/MCI  personnel:  Mr.  P.  Veckery,  Major  H.  Eiden,  Captain  R,  San 

Antonio,  and  Captain  W.  White  (Project  Officer). 

The  Software  Acquisition  Management  Guidebook  series  is  currently 
planned  to  cover  the  following  topics: 

1.  Project  Guide  to  Content  Requirement  and  Audience  Needs 

2.  Regulations,  Specifications  & Standards 

3.  Contracting  for  Software  Acquisition 

4.  Measuring  and  Reporting  Software  Status 

5.  Statements  of  Work  (SOW)  and  Requests  for  Proposal  (RFP) 

6.  Reviews  and  Audits 

7.  Configuration  Management 

8.  Requirements  Specification 

9.  Computer  Program  Documentation  Requirements 

10.  Verification 

11.  Validation  and  Certification 

12.  Management  Reporting  by  Software  Director 

13.  Computer  Program  Maintenance 

14.  Software  Quality  Assurance 

15.  Software  Cost  Estimating  and  Measuring 
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SECTION  I 


INTRODUCTION 


During  the  past  year  much  has  been  written  expressing  deep 
concern  about  the  problems  of  "Software  Acqusition  Management" 
(SAM):  the  management  of  software  specification,  procurement, 
integration,  and  maintenance  as  practiced  within  Air  Force  System 
Program  Offices  (SPO's). 

Symptoms  of  SAM  problems  acknowledged  to  date  include: 

• Failure  of  software  to  meet  the  acquirer's  and  user's 
quality  and  performance  expectations. 

• Failure  of  software  development  efforts  to  meet  projected 
schedules. 

• Failure  to  anticipate  accurately  the  resources  needed  to 
support  and  maintain  software  operating  in  the  field. 

• Failure  to  capture  useful  SAM  experience  in  the  form  of 
coordinated  standards  and  regulations. 

Production  of  a series  of  SAM  Guidebooks  is  one  activity  aimed 
at  reducing  these  problems.  Topics  to  be  covered  are: 

1.  Project  Guide  to  Content  Requirement  and  Audience  Needs 

2.  Regulations,  Specifications  & Standards 

3.  Contracting  For  Software  Acquisition 

4.  Measuring  and  Reporting  Software  Status 

5.  Statements  of  Work  (SOW)  and  Requests  for  Proposal  (RFP) 

6.  Reviews  and  Audits 

7.  Configuration  Management 

8.  Requirements  Specification 

9.  Computer  Program  Documentation  Requirements 

10.  Verification 
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11.  Validation  and  Certification 

12.  Management  Reporting  by  Software  Director 

13.  Computer  Program  Maintenance 

14.  Software  Quality  Assurance 

15.  Software  Cost  Estimating  and  Measuring 

This  technical  report  is  the  basis  for  the  first  volume,  intended 
to  serve  as  a guidebook  writer's  reference  before  and  during  the 
writing  process  in  matters  of  guidebook  planning,  user  profile,  and 
expository  and  editorial  style.  (Of  the  remaining  guidebooks,  topics 
2,  3,  4,  5,  and  9 have  been  or  are  being  developed). 

Whatever  its  topic,  each  guidebook  shares  with  the  others  a 
common  responsibility  to  provide  its  ultimate  user,  the  SPO's 
Software  Director  (SD),  with  three  general  classes  of  information: 

• Reference  and  index  lists  which  the  SD  can  use  to  access 

the  formal  regulations,  specifications,  and  standards 
relevant  to  the  topic  presented.  These  are  to  aid  him  in 
answering  the  question:  What  are  my  official  management 

opportunities  and  constraints  in  dealing  with  this 
particular  aspect  of  software  acquisition? 

• Explanations  (lessons  learned,  common  pitfalls,  mistaken 

assumptions,  etc.)  which  augment  official  guidance  with 
useful  experience.  This  kind  of  information  will  aid  the 
guidebook  user  in  answering  the  question:  Given  this  mass 

of  formal  definition  and  procedure,  how  do  I recognize  the 
most  significant  and  valuable  pieces  of  guidance,  how  can  I 
maneuver  effectively  and  safely  among  sometimes  conflicting 
sources  of  guidance,  and  are  there  any  serious  hidden 
implications  within  these  sources? 

• Checklists  and  descriptions  of  proven  software  acquisition 

management  techniques  which  answer  the  question:  What  are 

the  early  symptoms  of  common  SAM  problems  I might  encounter 
in  daily  operations,  and  what  tools  have  proven  effective 
in  the  past  in  monitoring  status,  in  identifying  problem 
thresholds,  and  in  re-creating  and  performing  post-mortems 
on  management  decisions? 
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Based  on  his  experience  in  the  field,  the  SAM  Guidebook  writer 
should  be  able  to  anticipate  his  reader's  natural  questions,  and  he 
should  tailor  his  guidebook  organization  and  content  accordingly. 
The  major  point  here  is  that  the  guidebook  writer  holds  all  the 
editorial  privileges  and  options:  in  matters  of  form  he  is 

initially  constrained  only  by  the  nature  of  his  material,  which 
itself  dictates  a best  form  of  presentation. 


PROJECT  GUIDE  TO  CONTENT  REQUIREMENTS  AND  AUDIENCE  NEEDS  - IN 
PERSPECTIVE 

Figure  1 places  the  PGCRAN  in  its  functional  slot  within  the 
guidebook  writing  process.  The  activity  flow  shows  the  guidebook 
writer's  SAM  judgement  and  experience  (hopefully)  playing  a part  in 
the  assignment  of  his  topic.  The  working  paper  ISTAO-SAM-OOl 
(extracts  appended  to  this  technical  report)  defines  for  the  writer  the 
boundaries  of  his  topic,  with  its  scope  drawn  in  terms  of  subtopics 
and  questions  that  each  particular  guidebook  must  answer.  Given 
topical  scope,  the  writer  can  dip  into  the  body  of  SAM  regulations, 
specifications,  and  standards  and  extract  the  formal  guidance 
relevant  to  his  topic.  This  formal  guidance,  plus  the  writer's 
experience  with  SAM  tools  and  procedures  plus  the  annotated  outline 
for  the  document  that  has  evolved  during  initial  research  comprise  the 
raw  data  from  which  the  finished  guidebook  will  be  constructed.  How 
does  the  PGCRAN  help  the  guidebook  writer  shape  his  material  into  the 
final  product? 

PGCRAN  - CONTENT  AND  FUNCTION 

The  following  section  of  this  guide  characterizes  the  SAM 
guidebook's  audience  in  terms  of  probable  background  and  software 
experience.  This  reader  profile  is  essentially  anonymous,  and  less 
useful  to  the  writer  than  his  own  personal  knowledge,  if  he  has  any, 
of  the  characteristics  of  SPO  personnel. 

With  the  guidebook  target  audience  defined,  the  writer  is 
concerned  with  methods  at  his  disposal  in  communicating  ideas  and 
sharing  experience.  Sections  III  and  IV  draw  a distinction  between 
expository  and  editorial  style  and  show  by  example  how  each  can  be 
used  to  achieve  effective  communication.  Section  V summarizes  the 
guidebook  writing  process  as  a series  of  tasks  from  initial  research 
to  final  review  of  the  completed  document. 

This  guide  is  neither  a substitute  for  experience  nor  a set  of 
editorial  rules.  We  attempt  here  only  to  raise  the  writer's 
consciousness  of  his  editorial  freedom,  and  to  suggest  some  proven 
techniques  for  expressing  his  ideas  and  experience  in  a readable 
way. 
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Figure  1.  Guidebook  Writing  Process 
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SECTION  II 


USER  PROFILE  AND  NEEDS 


The  following  sections  describe  the  guidebooks'  intended 
audience  and  their  needs  as  guidebook  users. 


GUIDEBOOK  USER'S  PROFILE 

The  guidebook  series  is  intended  for  use  by  System  Program 
Office  personnel,  specifically  the  military  officer  or  civilian 
assigned  as  Software  Director.  We  assume  the  SD  has  the  degree  of 
Air  Force  management  experience  implied  by  the  rank  of  Major,  and 
that  his  systems  engineering  experience  can  range  from  basic  to 
highly  advanced.  We  can  also  assume  that  although  the  SD  himself 
may  have  had  little  direct  experience  in  software  technology,  he  has 
at  his  disposal  the  technical  training  and  experience  of  junior 
officers  who  may  have  done  practical  work  in  the  field  or  studied 
computer  science. 

In  tailoring  his  product  for  the  intended  audience,  what  kind  of 
assumptions  can  the  guidebook  writer  make  about  the  SD's  software 
background? 

• The  SD  understands  general  differences  in  the  roles  of 
functional  and  non-functional  software  (executive  versus 
applications  programs). 

• For  the  system  whose  development  or  maintenance  he  is 
managing,  he  is  able  to  make  the  distinction  between  those 
functions  performed  by  software  and  those  performed  by 
hardware  (or  firmware). 

• He  is  aware  of  the  characteristics  of  major  inputs, 
outputs,  and  data  bases  processed  by  software. 

Once  outlined,  this  knowledge  envelope  provides  some  clear 
directions  in  the  guidebook  writer's  choice  of  technical  vocabulary. 
Because  he  knows  basic  EDP  operations  and  reads  the  trade  journals, 
the  SD  uses  terms  like: 

1)  compiler,  sort  program,  data  channel,  main  memory.  He  may 
be  familiar  with, 
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2)  firmware,  hardware  diagnostics,  program  loaders.  He  will 
not  deal  with, 

3)  reentrant  code,  Polish  notation,  relocation  dictionaries. 

We  sense  immediately  that,  based  on  our  arbitrary  classifica- 
tions, we  can  use  Group  1 terms  freely;  we  should  provide  defini- 
tions or  glossary  entries  for  Group  2 terms  as  required;  we  should 
avoid  Group  3 to  the  extent  possible.  The  SD  must  not  be  treated  as 
a software  beginner,  nor  should  we  draw  him  into  a maze  of  detail, 
no  matter  how  technically  exciting. 


USER'S  NEEDS 

For  each  guidebook,  ISTA0-SAM-001  defines  the  user's  needs  for 
specific  topical  content,  and  repetition  here  would  serve  little 
purpose.  In  general,  however,  the  SD  does  not  need  or  want  another 
set  of  regulations,  nor  an  education  in  management  or  computer 
science.  He  can  only  reasonably  expect  any  guidebook  to  provide  him 
with  the  three  basic  kinds  of  information  mentioned  earlier: 
references  to  applicable  regulations,  specifications,  and  standards; 
advice  on  how  to  work  within  articles  of  official  guidance;  good 
advice  on  management  techniques  to  be  employed  in  response  to  common 
problems.  And  it  is  desirable,  to  the  extent  possible,  to  transmit 
these  kinds  of  information  in  the  form  of  concise  checklists  rather 
than  masses  of  rambling  narrative  text. 

To  respond  to  these  user  needs  appears  to  involve,  at  first 
inspection,  the  conventional  kind  of  technical  writing  effort  that's 
used  to  produce  the  SAM  regulations,  specifications,  and  standards 
themselves.  More  is  required.  If  we  really  intend  "to  pass  on 
experience"  as  we  claim,  then  the  guidebook  writing  task  takes  on 
some  journalistic  elements  with  the  need  to  report  past  experiences 
and  to  take  an  editorial  position. 

This  is  a delicate  point.  Much  of  the  experience  we  hope  to 
pass  on  to  the  SD  revolves  around  choices  made  and  options  exercised 
in  the  past  with  positive,  neutral,  or  negative  results.  To 
advocate  a particular  choice  in  preference  to  others  is  to  take  a 
position,  and  in  taking  a position  the  writer  obligates  himself  to 
reveal  the  reasons  behind  his  position.  The  writers  of  regulations, 
specifications,  and  standards  are  under  no  similar  obligation:  RS&S 

documents  say  "do  this,"  while  the  guidebook  should  say  "we  suggest 
doing  this  because. . .and  here  are  the  pro's,  con's,  advantages,  and 
dangers  in  proceeding  this  way...." 
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At  the  same  time,  guidebook  writers  must  beware  of  erring  in  the 
opposite  direction  by  presenting  overly  detailed  justifications  and 
lengthy  case  studies  for  the  following  reasons: 

• The  best  natural  organization  of  a guidebook  could  be 
ruined  if  its  material  had  to  be  warped  around  one  or  more 
case  studies. 

• It  would  be  difficult  to  disguise  the  identity  of  actual 
programs.  The  intent  is  to  pass  on  experience  rather  than 
implied  criticism  or  gossip. 

• Transition  into  and  out  of  past  tenses  could  be  awkward  and 
distracting  to  the  reader. 

Between  the  two  extremes  (checklists  and  case  studies)  lies  the 
technique  of  presenting  selected  incidents  which  illustrate  the 
reasons  behind  a position  or  recommendation.  The  following  example 
is  drawn  from  the  U.S.  Army  Tactical  Data  Systems 's  "Software 
Acquisition  Handbook,"  Fort  Monmouth,  15  June  1973: 

"Consider,  for  example,  a test  involving  radar  data.  During  the 
test,  it  is  noticed  that  there  is  multiple  registration  of  radar 
returns.  The  problem  could  be  due  to  atmospheric  conditions, 
radar  set  malfunction,  noise  on  the  communication  lines  bringing 
the  radar  message  to  the  computer,  incorrect  adaptation  for  one 
or  more  radar  sites,  software  error  in  the  processing  of  the 
return,  or  a software  error  in  displaying  the  return.  Problems 
of  this  sort  demand  a great  deal  of  data  reduction  during  the 
diagnostic  phase  simply  to  pinpoint  the  malfunctioning 
subsystem.  The  acquirer  may  need  to  provide  coordination 
between  the  software  and  hardware  contractors  to  ensure  complete 
diagnosis  of  the  problem." 

Persuasive  advocacy  often  adds  a desirable  vitality  to  otherwise 
neutrally  dry  writing.  An  editorial  point  of  view  also  gives  the 
guidebook  writer  a sense  of  direction  to  use  in  getting  started  on 
any  subtopic,  and  in  subsequently  shaping  his  material.  The 
following  two  sections,  covering  narrative  and  editorial  style, 
provide  some  guidelines  to  be  used  in  the  shaping  process. 
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SECTION  III 


EXPOSITORY  STYLE 


DEFINITION 

Although  the  term  "style"  as  applied  to  the  guidebook  series  to 
date  is  open  to  many  interpretations,  we  make  the  arbitrary 
distinction  here  between  expository  and  editorial  style.  Expository 
style  refers  to  the  manner  of  expression  employed  in  communicating 
ideas  to  a reader.  Editorial  style  refers  to  a set  of  structual 
formalisms  and  editorial  conventions  used  in  constructing  a 
document,  independent  of  conceptual  content.  (For  example,  one 
authority  on  editorial  style,  the  U.S.  Government  Printing  Office 
Style  Manual,  concerns  itself  with  such  conventions  as  standard 
heading  labels  and  subordination,  capitalization,  abbreviations, 
footnote  formats,  type  styles,  and  so  forth.)  Matters  of  editorial 
style  are  addressed  in  the  following  section.  As  discussed  below, 
expository  style  is  composed  of  mode  of  presentation  and  tone. 

Mode 


Ideas  may  be  communicated  to  the  guidebook  reader  using  any  of 
three  general  modes  of  presentation: 

• Graphics  - Those  are  pictures  of  all  types:  PERT  Charts, 

flowcharts,  histograms,  etc. 


• Lists  - Lists  may  be  ordered  or  unordered,  composed  of 
single  words,  sentence  fragments,  or  entire  paragraphs. 

• Text  - This  is  conventional  narrative,  organized 
arbitrarily  into  sections,  subsections,  paragraphs,  or 
whatever  units  are  dictated  by  the  editorial  style  adopted. 

The  above  is  not  presented  simply  for  the  sake  of  definition, 
but  to  help  make  a very  important  point:  every  idea,  every  concept 

that  the  guidebook  writer  wants  to  communicate  to  his  reader  has  a 
best  mode  of  presentation.  The  choice  is  the  writer's,  to  be  made 
free  of  any  editorial  conventions,  based  on  the  writer's  intimate 
knowledge  of  his  material  and  his  immediate  objectives  in 
communicating  it. 
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Editorial  style  conventions  cannot  govern  choice  of  mode,  only 
the  structural  formalisms  applicable  to  the  mode  selected.  To 
enforce  modal  standards,  to  require  synchronization  of  content  type 
with  mode,  inhibits  effective  communication.  The  writer  who  begins 
his  guidebook  development  task  by  studying  an  editorial  style  manual 
has  made  the  worst  possible  start.  . Editorial  conventions  are  not  a 
point  of  departure,  and  they  do  not  set  limits  on  effective 
communication  of  ideas. 

Tone 


Why  do  so  many  civilian  and  military  managers  prefer  to  receive 
information  in  the  form  of  briefings,  in  preference  to  reading 
narrative  text?  Because  the  human  voice  can  express  shades  of 
meaning  which  are  very  difficult  to  compress  into  reasonably  sized 
sequences  of  written  language,  and  because  face-to-face 
communication  is  a natural  function,  a more  interactive  and 
satisfying  experience  than  the  scanning  of  a printed  page. 

But  the  use  of  dialogue  is  not  appropriate  to  the  guidebook 
series:  we  write  narrative  text,  not  quoted  human  speech.  The  very 

best  narrative  text,  however,  captures  something  of  the  tone  of 
human  speech  in  communicating  even  abstract  ideas. 

Given  that  we  recognize  tone  or  quality  of  human  speech  as  a 
desirable  feature  of  guidebook  narrative  text,  we  must  choose  the 
kind  of  tone  likely  to  maximize  the  reader's  absorption  of  the  ideas 
we  want  to  transmit.  The  very  short  list  below  bounds  a tonal  range 
that  seems  generally  appropriate  to  the  guidebook  effort. 

(Naturally,  each  writer  has  his  opinions  and,  in  fact,  tonal 
requirements  change  with  the  kind  of  material  presented  and  the 
relative  emphasis  to  be  placed  upon  it.) 

Writer 

Should  But 

Sound  Not 


in  charge  of  his  material  commanding  or  condescending 

pleasant  chatty 

persuasive  contentious 

The  example  below,  drawn  from  the  draft  of  the  "Contracting" 

guidebook,  fits  nicely  within  this  tonal  envelope: 

"The  formal  acquisition  process  sometimes  gives  the  appearance 
of  a maze  of  mysterious  rules  and  regulations,  understandable 
only  by  lawyers,  which  define  in  great  detail  what  can't  be 
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done.  The  software  manager  should  not  accept  this  appearance  as 
the  real  situation.  Instead,  he  should  first  decide  what  he 
wants  to  do  and  then  insist  that  the  acquisition  experts  figure 
out  how  to  do  this  within  the  framework  of  the  procurement 
regulations.  The  ASPR  is  surprisingly  permissive  in  allowing 
the  exercise  of  judgment  and  reason  throughout  the  acquisition 
process. " 

Notice  how  the  quotation  above  not  only  demonstrates  attractive 
tonal  features,  but  also  takes  an  editorial  position  as  suggested  in 
Section  II. 

The  following  is  another  example  drawn  from  the  Army  Tactical 
Data  System's  "Software  Acquisition  Handbook."  Note  that  it  is 
somewhat  more  formal  in  language  but  far  from  monotonal,  since  its 
punctuation  creates  some  natural  speech  rhythms  and  inflections. 

"Tradeoffs,  of  course,  must  be  made  relative  to  each  candidate 
ECP.  If  its  omission  is  such  that  the  test  cannot  continue  (due 
to  a system  loop  or  halt)  or  results  are  valueless,  then  there 
is  no  question  but  that  it  must  be  incorporated  even  if  its 
installation  and  checkout  delay  the  initiation  or  continuation 
of  qualification  testing.  But  some  ECPs  do  not  bear  this 
importance  - and  their  incorporation  into  the  CPCI  can  await 
completion  of  the  FQT." 

The  guidebook  writer  creates  tone  by  making  choices  from  among  a 
multitude  of  options  of  mood,  voice,  punctuation,  vocabulary,  and 
sentence  structure.  One  way  of  injecting  tone  is  to  invent,  or 
adopt,  a comprehensive  set  of  rules  governing  usage  of  these 
language  elements:  "never  use  the  passive  voice,"  "use  contractions 
where  possible,"  "always  underscore  absolute  or  pivotal  words  like 
not,  always . unless. " "mix  up  usage  of  indicative,  imperative,  and 
subjunctive  moods,"  etc.  This  approach,  however,  tends  to  produce  a 
mechanical,  cookbook  writing  process  which  stifles  spontaneity  of 
communication.  There  is  another  way. 


Keeping  a mental  image  of  the  intended  reader's  profile  before 
him,  the  guidebook  writer  can  visualize  himself  in  an  informal 
blackboard  briefing  situation  and  write  in  the  relaxed  verbal  style 
he  would  use  in  explaining  technical  and  management  issues  to  an 
audience  of  one.  This  technique  forces  the  writer  to  create 
appropriate  tonal  variations  in  spite  of  himself  as  verbal  gestures 
are  translated  into  narrative  text.  The  more  spontaneous  and 
informal  the  process,  the  better:  lapses  in  narrative  construction, 
formality,  and  other  elements  are  easily  repaired  later.  The 
important  point  is  to  get  moving  with  the  story  and  to  get  its 
essentials  down  straight. 
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SECTION  IV 


EDITORIAL  STYLE 


This  kind  of  style,  as  distinct  from  expository  style,  deals 
with  conventions  external  to  the  idea'  content  of  the  guidebook:  it 

governs  the  packaging  of  the  modes  of  presentation  which  carry  the 
ideas.  Because  of  the  very  large  numbers  of  editorial  style  sources 
potentially  available  for  review  and  evaluation,  we  are  fortunate 
that  the  nature  of  the  guidebook  project  dictates  use  of  a single, 
unconstraining  source:  MIL-STD  847A. 


THE  STANDARD 

"Format  Requirements  for  Scientific  and  Technical  Reports 
Prepared  by  or  for  the  Department  of  Defense"  (MIL-STD  847A) 
presents  guidance  of  an  extremely  general  nature.  (The  only 
mandatory  contents  of  a technical  report,  for  example,  include  a 
completed  DD  Form  1473  plus  front  and  back  covers.)  Although  the 
standard  does  not  mandate  a chapter /section/paragraph  identification 
scheme,  it  does  define  a required  sequence  of  sections  by  type  when 
such  sections  are  included : 

(front  matter) 

Front  Cover 

Report  Documentation  Page,  DD  Form  1473 

Summary 

Preface 

Table  of  Contents 
List  of  Illustrations 
List  of  Tables 

(body  of  report) 

Introduction 
Main  Text 
Conclusions 
Recommendations 

(reference  material) 

References 
Bibliography 
Appendices 
Glossary  of  Terms 

List  of  Abbreviations,  Acronyms,  and  Symbols 
Index 
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Distribution  List 
Back  Cover 

Beyond  this,  the  standard  specifies  that  headings  and  paragraphs 
need  be  numbered  "only  when  needed  for  clarity."  We  may  choose  to 
adopt  a numbering  scheme  such  as  the  standard  decimal  progression 
(1.0,  1.1,  1.1.1,  etc.)  or  one  of  many  others.  The  decision  can 
remain  open  to  negotiation  at  this  point  since  no  great  effort  is 
involved  in  retrofitting  a draft  document  with  a numbering  system. 


THE  OUTLINE 

While  the  editorial  style  guide  adopted  ultimately  provides  a 
labeling  and  label  subordination  system  for  the  guidebook's  various 
units  of  information,  it's  the  guidebook  writer  who  defines  the 
information  contents  and  conceptual  interrelationships  of  these 
units  by  means  of  an  evolving  outline. 

The  first  stage  requires  preparation  of  a topical  outline,  an 
unordered  list  of  subtopics  which  the  writer  feels  are  applicable  to 
the  guidebook  topic  and  which  he  believes  can  be  fleshed  out 
reasonably  using  the  materials  at  his  disposal.  Verifying  his 
topical  outline  against  his  material  and  organizing  subtopics  into 
larger  units  as  necessary,  the  writer  creates  an  ordered  list  of 
sections  together  with  a set  of  notes  summarizing  the  content  and 
objectives  of  each.  This  is  termed  an  annotated  outline,  the  point 
of  departure  of  the  writing  process  itself.  The  annotated  outline 
must  be  delivered  to  the  Air  Force  Project  Office  for  formal  review 
and  concurrence. 

Because  the  writer  should  be  left  free  to  organize  his  material 
in  whatever  fashion  it  best  presents  itself,  restrictions  and 
constraints  on  the  outline  process  should  be  minimal.  And,  in  fact, 
the  guidebook  outlines  developed  to  date  do  show  differing 
orientations,  variously  keyed  to: 

• the  typical  sequence  of  software  acquisition  management 
events, 

• the  relative  magnitude  of  SAM  tasks, 

• the  relative  significance  of  SAM  regulations, 
specifications,  and  standards. 

AF  pamphlet  10-1  "Guide  for  Air  Force  Writing,"  provides  some 
excellent  advice  to  the  guidebook  writer  on  the  outlining  process: 
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"NOTE:  Don't  let  the  making  of  an  outline  slow  you  down.  The 
more  complete  you  make  it,  the  easier  it  will  be  for  you  to 
write  from  it  later,  but  it  doesn't  have  to  be  'perfect.' 

Laboring  over  an  outline  until  it  details  everything  can  be  a 
waste  of  time  and  effort.  It  would  be  better  to  just  jot  your 
main  ideas  on  paper  and  use  them  as  a guide." 

Beyond  the  desirable  freedom  to  organize,  there  is  a very  small 
set  of  minimum  mandatory  content  items  which  cut  across  all  guidebook 
projects.  These  include  a glossary  of  terms  (see  Section  II),  checklists 
of  management  guidance  references  and  management  procedures,  a discussion 
of  applicable  Regulations,  Specifications,  and  Standards  and  lessons 
drawn  from  experience. 


I 
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SECTION  V 


WRITING  THE  GUIDEBOOK 


Although  each  guidebook  writer  will  have  his  own  attitudes 
toward  writing  and  his  own  personal  methods  of  turning  out  copy,  we 
can  define  (at  a very  high  level)  a set  of  production  steps  which 
seem  to  apply  sensibly  across  all  guidebook  development  projects. 
The  sections  below  describe  two  preparatory  steps  and  two  writing 
and  editing  steps  to  be  utilized  in  writing  each  guidebook. 


ASSEMBLING  AND  ANALYZING  MATERIALS 

The  writer  analyzes  content  and  boundaries  of  his  topic  as 
defined  by  ISTA0-SAM-001 . He  alters  the  boundaries  as  required  in 
accordance  with  his  experience  and  knowledge,  negotiating  such 
changes  with  the  Air  Force  Project  Office  which  must  maintain 

centralized  control  of  guidebook  scope.  ' 

The  writer  identifies  the  portions  of  existing  SAM  regulations, 
specifications,  and  standards  which  are  relevant  to  his  topic  and  4 

analyzes  them,  based  on  his  experience,  in  terms  of  gaps,  overlap, 
and  conflict.  To  those  sources  of  formal  guidance  he  adds  informal 
sources  drawn  from  industry,  government  agencies,  and  interviews 
with  experienced  personnel  including,  if  possible,  those  with  System 
Program  Office  experience.  Based  on  these  materials,  the  writer 
develops  reference  lists  of  useful  SAM  tools  and  techniques. 

In  parallel  with  the  above  tasks,  the  writer  works  with  an 
evolving  guidebook  outline.  He  is  left  free  to  rearrange  his 
outline  as  his  material  develops  inside  or  outside  it,  constrained 
only  to  organize  the  material  in  a way  that  seems  natural  for  most 
effective  presentation  (as  discussed  in  Section  IV).  This  outline, 
first  in  topical  then  in  annotated  form,  will  be  reviewed  by  the 
Air  Force  Project  Office  in  accordance  with  the  procedure  outlined 
in  Figure  1. 


1 
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VERIFYING  FEASIBILITY  AND  SCOPE 


If  a major  overlap  in  topical  boundaries  is  identified,  the 
materials  developed  to  this  point  (reference  lists  of  management 
guidance  and  techniques)  could  be  turned  over  to  another  guidebook 
whose  scope  would  be  adjusted  accordingly.  The  object  is  to  prevent 
heavy  expenditures  of  manpower  on  a product  whose  content  promises 
to  add  little  in  interpretation  or  experience  to  the  basic  official 
guidance.  However,  the  Air  Force  Project  Office  must  concur  with 
this  action. 


WRITING  AND  EDITING 

The  writer  reviews  this  guide  once  more  and  moves  into  the  writing 
phase,  producing  text,  lists,  and  graphics  for  each  subtopic  as  fast 
as  possible  while  striving  for  spontaneity  of  tone  as  suggested  in 
Section  III.  The  writer  is  careful  not  to  begin  with  the  guidebook 
introduction  since  he  knows  that  effective  introductory  material  can 
be  written  only  after  the  content  to  be  introduced  is  written  and 
thoroughly  understood.  He  also  guards  against  an  over-consciousness 
of  the  editorial  style  guidelines  to  be  applied  later. 

With  most  of  his  guidebook  content  developed  in  piecemeal 
fashion,  the  writer  must  arrange  his  fragments  in  a natural  best 
sequence  (referencing  his  earlier  intentions  as  reflected  by  his 
annotated  outline).  This  done,  he  must  label  and  link  sections 
together  by  writing  transitional  material  in  accordance  with  the 
structural  requirements  of  the  editorial  style  adopted.  An  editing 
pass  is  then  needed,  driven  by  guidance  from  two  sources:  the 

editorial  style  conventions,  and  editing  techniques  drawn  from  the 
checklists  published  in  any  one  of  the  many  writing  guides  available. 

AF  Pamphlet  10-1,  Guide  for  Air  Force  Writing,  is  a useful  document. 

One  of  the  many  checklists  it  contains  is  attached  here  as  Appendix  II. 

With  first  draft  written  and  edited,  the  guidebook  draft  is  sub- 
mitted to  the  Air  Force  Project  Office  for  review.  Gathering  the 
comments  thus  generated,  the  guidebook  writer  produces  the  final  draft 
for  this  guidebook  (in  the  form  of  a 40-75  page  technical  report). 
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APPENDIX  I 


Extracts  from  ISTA0-SAM-001  which  outline  the  topical  boundaries 
of  each  of  the  proposed  software  acquisition  management  guidebooks. 
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GUIDE  TO  REGULATIONS,  SPECIFICATIONS,  AND  STANDARDS 


This  guidebook  will  provide  a topical  index  and  description  of 
regulations,  specifications  and  standards  that  are  pertinent  to  the 
management  and  development  of  software.  Inconsistencies  between 
regulations,  specifications  and  standards  will  be  identified  to  the 
extent  possible.  Where  appropriate,  it  will  provide  a discussion  of 
the  impact  and  requirements  that  these  documents  impose  on  the 
software  development  cycle,  and  on  the  system  acquisition  life  cycle 
(AFR  800-2).  Appropriate  matrices  will  be  included  to  indicate: 

(1)  the  applicability  of  a particular  regulation's  specifications 
and  standards  to  specific  acquisition  classes  and  (2)  the 
applicability  of  a standard  specification  and  standard  at  any  point 
in  the  acquisition  life  cycle.  Points  covered  by  this  volume  are: 

• How  should  regulations,  specifications  and  standards  (R,  S, 
S)  be  used,  and  at  what  points  in  the  life-cycle? 

• What  R,  S,  S are  pertinent  to  software  acquisition;  how  do 
they  apply  to  areas  covered  in  other  sections  of  this 
guide? 

• How  can  one  resolve  inconsistencies  or  conflicts  in  R,  S, 

S? 

• For  each  R,  S,  S,  briefly  summarize  its  contents. 

• Provide  a topic  index  to  R,  S,  S's. 


CONTRACTING  FOR  SOFTWARE  ACQUISITION 

This  guidebook  will  address  the  contractual  aspects  of  software 
procurement  starting  with  advanced  procurement  planning  and  ranging 
to  contract  management.  Topics  include:  contract  type  selection, 
contractor  selection,  proposal  evaluation  and  contract  management 
techniques.  Questions  answered  by  this  guidebook  are: 

• What  types  of  contracts  deal  exclusively  with  software  or 
have  software  components? 

• What  contractual  provisions  do  or  should  pertain  especially 
to  software? 

• What  are  the  pitfalls  in  software  contracting  and  how  can 
they  be  avoided? 
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What  provisions  in  the  contract  are  required  for  protection 
of  classified  information? 


MEASURING  AND  REPORTING  SOFTWARE  STATUS 

The  purpose  of  this  guide  is  to  describe  available  methods  for 
assessing  the  status  of  the  software  development  effort  and  to 
identify  problem  areas  and  shortcomings  encountered  in  their  use. 

It  will  tell  the  manager  what  information  to  look  for,  where  to  get 
it  and  how  to  use  it  to  measure  the  progress  of  the  development 


effort. 

are: 

Some  of  the  questions  for  which  guidance  will  be  provided 

• 

What  methods  are  available  for  determining  the  status  of 
developmental  software? 

• 

What  types  of  reports  or  measuring  devices  should  be 
imposed  and  what  should  they  contain  as  data? 

• 

How  frequently  should  milestone  or  checkpoint  reports  be 
required? 

STATEMENTS  OF  WORK  AND  REQUESTS  FOR  PROPOSAL 

This  guidebook  describes  the  content  and  format  of  SOWs  and 
RFPs.  It  identifies  the  organizational  responsibility  for  their 
initial  development  and  the  process  for  initiating  and  controlling 
changes.  Emphasis  is  placed  on  common  pitfalls  in  SOW  and  RFP 
writing.  Questions  answered  by  the  guidebook  are: 

How  to  Write  a Software  SOW  or  RFP 


# 

What  are  appropriate  contents? 

• 

What  regulations,  specifications  and  standards  should  be 
identified? 

• 

How  can  one  determine  the  adequacy  of  each  provision?  What 
pitfalls  are  common? 

• 

Where  does  a SOW  or  an  RFP  fit  in  the  software  life-cycle? 

• 

i 

What  provisions  should  be  made  for  software  data  rights? 
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What  Can  be  Done  if  the  SOW  or  RFP  is  Already  Written  and 
Inadequate? 

• Formal  amendment 

• Other  means  for  establishing  agreement 


REVIEWS  AND  AUDITS 

This  guide  will  list  and  describe  design  reviews  and  audits 
required  by  existing  AF  directives.  It  will  indicate  the 
organizational  element  responsible  for  conducting  a design  review  or 
audit  and  describe  when  and  how  the  review  or  audit  will  be 
conducted. 

Typical  reviews  and  audits  required  for  software  acquisition 

are: 

• System  Design  Review 

• Software  Preliminary  Design  Review 

• Software  Critical  Design  Review 

• Progress  Reviews  during  Development  and  Programming 

• Progress  Reviews  during  Verification,  Validation  and  -t 

Certification 

• Functional  Configuration  Audit 

• Physical  Configuration  Audit 

The  guidebook  will  answer  the  following  questions  for  each 
review  or  audit  listed  above: 

• What  material  should  be  available  before  each  review  or 
audit? 

• What  steps  are  involved? 

• Who  will  or  should  be  there? 

• What  documents  should  result? 

• If  corrective  action  is  needed  because  of  a review  or 
audit,  how  is  the  action  implemented? 

v 

• If  previous  reviews  or  audit  have  not  occurred  or  have  not 
been  resolved,  what  alternatives  are  available  for  action? 

.1 

• To  what  level  of  detail  should  a review  or  audit  go? 
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Who  will  use  the  results  of  the  review  or  audit  and  what 
for? 


CONFIGURATION  MANAGEMENT 

This  guidebook  will  describe  how  the  configuration  baseline  is 
established  and  controlled  throughout  the  development  life-cycle. 
Particular  emphasis  will  be  placed  on  techniques  for  enforcing  sound 
configuration  management  procedures.  Some  of  the  questions 
addressed  by  this  guidebook  are: 

• Baseline  management  - what  is  it? 

• What  establishes  a baseline? 

• What  baselines  are  maintained,  and  when  are  they 

maintained? 

• When  is  formal  configuration  control  placed  on  the  software 
development? 

• When  is  informal  (e.g.,  contractor's  in-house  configuration 

management)  configuration  control  desirable? 

• What  type  of  organization  is  required  to  maintain  control 
over  the  software  configuration? 

• Who  participates? 

• What  does  a typical  configuration  management  plan  look 
like? 

• Changes  and  waivers  - how  does  one  make  changes  to 
baselines? 


REQUIREMENTS  SPECIFICATION 

This  guidebook  describes  the  content  of  the  functional 
requirements  and  functional  specifications  documents.  It  provides 
guidance  on  who  prepares  the  requirements  document,  who  reviews  and 
approves  them,  and  how  they  are  to  be  used  during  subsequent  phases 
of  the  acquisition  life-cycle.  Some  of  the  questions  to  be  answered 
by  this  guidebook  are: 
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• Software  requirements  documents  - what  should  they  contain 
and  what  should  be  done  if  they  don't? 

• Who  reads  them,  what  does  he  do  with  them,  and  what  does  he 
need  from  them? 

• What  is  the  relation  of  software  specifications  and 
requirements  documents  to  "system"  specifications  and  other 
documents? 

• How  can  software  requirements  best  be  stated  (i.e.,  in  what 
terms;  to  what  detail)? 

• What  aids  are  available  for  stating  requirements? 

• From  whose  point  of  view  should  the  requirements  be  stated? 

• How  are  the  software  security  requirements  established? 


COMPUTER  PROGRAM  DOCUMENTATION  REQUIREMENTS 

For  each  of  the  following  documents,  who  is  it  intended  for;  who 
writes  it;  what  are  its  appropriate  contents;  where  are  oversights 
frequently  made;  what  documents  describe  their  form  and  format;  what 
is  an  appropriate  level  of  detail;  how  does  one  re-create  the 
document  if  it  is  missing  or  was  improperly  written;  when  is  it 
unnecessary;  how  is  it  updated;  how  can  one  tell  if  it's  any  good; 
what  are  the  corresponding  data  items  (TD-3);  what  standards  apply; 
how  is  a security  classification  determined? 

• System  Specification 

• Computer  Program  Development  Specification  (Part  I Spec) 

• Computer  Program  Product  Specification  (Part  II  Spec) 

• Lower  Level  Specification  (Program  module,  subroutine) 

• Programmer's  Manual 


Operator's  Manual 

User's  Manual  or  Positional  Handbook 
Program  Catalogs  and  Listings 
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• Maintenance  Documentation  (set/used  listings,  change 
notices) 

• Training  Aids 

• Data  Base  Document  and  Listings 

• Interface  Specifications 

• Version  Descriptions 


s 
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VERIFICATION 

Verification,  in  this  context,  is  the  process  of  determining 
equivalency  between  the  different  representations  of  the  software 
that  are  products  of  the  software  development  process.  Verification 
tools  and  techniques  are  the  means  for  accomplishing  the  goals  and 
tasks  that  are  identified  in  the  formal  review  process  (ref  MIL-STD- 
1521).  Using  references  as  much  as  possible,  this  guide  will 
describe  the  manual  techniques  employed  for  verifying  requirements, 
specifications,  and  code.  It  will  further  identify  automated  aids 
that  are  available  to  assist  the  verification  process.  Emphasis  will 
be  placed  on  describing  various  strategies  that  can  be  employed  by 
the  software  manager  to  obtain  the  necessary  resources  (tools, 
personnel,  computer,  etc.)  to  successfully  accomplish  verification 
(e.g.  Independent  Verification  Contractor,  Independent  Air  Force 
Agency,  etc.)  The  guide  will  further  identify  the  manner  in  which 
these  resources  should  be  organized,  directed  and  controlled. 
Questions  to  be  answered  by  this  guidebook  are: 

• What  software  acquisition  deliverables  require 
verification? 

• How  are  the  verification  criteria  for  a particular 
deliverable  established  and  where  are  they  specified? 

• At  what  points  in  the  acquisition  life-cycle  is 
verification  accomplished? 

• Who  is  responsible  for  accomplishing  the  verification? 

• What  tools  are  available  for  verifying  software? 

• What  actions  are  taken  if  software  products  fail  the 
verification? 
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VALIDATION  AND  CERTIFICATION 


Software  validation  and  certification  are  similar  to  software  * 

verification.  They  differ  primarily  in  the  span  of  software 
development  activities  to  which  the  validation  or  certification 
process  is  applied.  The  validation  process  establishes  whether  or 
not  the  completed  computer  programs  meet  the  system  specification; 
certification  establishes  whether  or  not  the  completed  computer 
programs  satisfy  the  mission  requirements.  The  guidebook  will 
address  the  techniques  for  validating  and  certifying  software  and 
will  cite  pertinent  standards, specifications  and  regulations  related 
to  the  validation  and  certification  process.  Automated  tools  to 
facilitate  validation  and  certification  will  be  identified. 

Questions  to  be  addressed  in  the  guidebook  are: 

• What  organizational  element  of  the  development  activity  is 
responsible  for  validation?  For  certification? 

* 

• Who  provides  the  resources  for  certification  and 
validation? 

• What  reports  are  provided  to  indicate  the  results  of  * 

certification  and  validation? 

• What  actions  are  taken  if  the  computer  programs  fail 
validation  or  certification? 

• Who  establishes  the  validation  and  certification  plan  and 
schedule? 


MANAGEMENT  REPORTING  BY  PROJECT  DIRECTOR 

This  guidebook  lists  the  formal  reports  required  by  directives 
governing  the  software  acquisition  process  and  the  informal  reports 
dictated  by  good  management  practices.  Emphasis  is  placed  on  the 
need  to  provide  meaningful,  quantified,  indications  of  where  the 
project  stands  in  relation  to  cost  and  schedules. 

• What  types  of  reports  are  required? 

• By  whom? 

• What  goes  into  a report?  Where  does  one  find  the  required 
information? 
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• What  are  the  commonly  accepted  variables  for  assessing 
software  status? 

• How  valid  are  they? 

• How  much  flexibility  does  one  have  in  preparing  reports, 
how  often  must  they  be  given,  where  does  one  look  for 
additional  direction  (guidance)? 


COMPUTER  PROGRAM  MAINTENANCE 

This  guidebook  will  emphasize  the  need  for  considering  future 
maintenance  of  the  software  during  each  step  of  the  development 
process.  Appropriate  Air  Force  and  DoD  directives  specifying 
maintainability  requirements  will  be  cited.  The  following  questions 
will  be  answered. 

• What  materials  (documents,  versions  of  programs,  plans, 
facilities,  etc.)  must  be  available  for  maintenance? 

• What  is  an  appropriate  organization  for  maintenance? 

• What  special  procedures  must  be  instituted  for  maintenance? 

• How  can  one  estimate  the  time  and  costs  for  maintenance? 

• Who  in  the  development  organization  is  responsible  for  ensur- 
ing that  end  product  maintenance  provisions  are  adequate? 


SOFTWARE  QUALITY  ASSURANCE 

This  guidebook  will  identify  and  define  elements  of  software 
quality  assurance,  and  provide  guidelines  for  managing/conducting  a 
quality  assurance  program.  Topics  will  include:  definition  of 
software  quality,  methods  of  quality  measurement,  techniques 
(configuration  management,  test  management,  data  management, 
requirements  traceability,  etc.),  contractual  aspects  of  quality 
assurance. 

Questions  to  be  answered  by  this  guidebook  include: 

• What  type  of  scheduled  events  or  milestones  should  occur  in 
a software  quality  assurance  (SQA)  program? 
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• Who  should  perform/use  the  SQA  techniques  (Air  Force  in- 
house,  FCRC,  prime  software  contractor,  independent 
contractor)? 

• What  types  of  deliverables  should  be  expected  from  an  SQA 
program? 

• What  type  of  corrective  action  should  occur  if  SQA  program 
detects  faulty  design  or  coding? 


SOFTWARE  COST  ESTIMATING  AND  SCHEDULING 

This  guidebook  tells  how  software  development  cost  and  schedule 
estimates  are  established.  Emphasis  is  placed  on  the  techniques  for 
measuring  and  controlling  costs  and  schedule  during  the  development 
life-cycle.  Questions  to  be  answered  by  this  guidebook  are: 

• How  can  one  estimate  development  costs,  maintenance  costs, 
life-cycle  costs  of  software? 

• What  are  the  components  of  software  development  costs?  ' 

• How  do  cost  analyses  and  predictions  relate  to  work 

breakdown  structures  (MIL-STD-881 )?  i 

• What  methods  are  available  for  measuring  budget 
conformance? 

• What  methods  are  available  for  recovering  from  real  or 
predicted  budget  overruns? 
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APPENDIX  II 

CHECKLIST  FOR  REVIEWING  AND 
EVALUATING  WRITING 

Technical  Evaluation  Writing 


1.  Does  it  fulfill  objectives? 

2.  Does  it  cover  essential 
points? 

3.  Does  the  preface  or  intro- 
duction explain  what  is  to 
come  and  in  what  order? 

4.  Are  the  proper  acknowledg- 
ments and  assumptions 
included? 

5.  Is  the  problem  stated  so 
that  it  agrees  with  the 
objectives? 

6.  Are  the  conclusions  or  rec- 
ommendations significant, 
pertinent,  and  valid? 

7.  Are  the  findings  supported 
by  the  data  presented? 

8.  Does  the  main  discussion  or 
body  describe  the  data, 
tests,  procedures,  etc., 
with  completeness  and 
accuracy? 

9.  Are  specific  sources  given 
for  all  information? 

10.  Are  all  source  materials 
in  the  public  domain  (for 
example,  available  through 
the  National  Technical 
Information  Service)? 

11.  Is  the  information  exact 
and  accurate? 


1 . Is  the  arrangement  and  order 
of  presentation  well-balanced? 

2.  Is  there  a suitable  title 
page,  table  of  contents,  list 
of  illustrations  (if  needed)? 

3.  Is  the  writing  clear,  un- 
ambiguous, precise,  and 
readable? 

4.  Are  the  sections  and  subsec- 
tions identified  with  ac- 
curate and  interesting 
headings? 

5.  Are  the  typographical 
errors  corrected  or  marked 
for  correction? 

6.  Is  the  typing  clean  enough 
for  the  purpose  for  which 
the  document  is  to  be  used? 

7.  Are  the  illustrations, 
charts,  and  tables  (if 
any)  accurately  numbered 
for  identification?  Do  they 
appear  near  the  data  they 
support?  Are  they  refer- 
enced to  the  sections  they 
support? 

8.  Is  the  level  of  language 
appropriate  to  the 
readers: 

a.  Too  technical? 

b.  Too  bureaucratic? 

c.  Too  much  jargon? 


Evaluation 

9.  Are  abbreviations  and  new 
terms  explained? 

10.  Is  the  transition  adequate 
from  topic  to  topic,  para- 
graph to  paragraph,  and 
sentence  to  sentence? 


